<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>mbox: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">mbox
   </div>
   <div id="projectbrief">Vitis Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Overview</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="globals.html"><span>APIs</span></a></li>
      <li><a href="files.html"><span>File&#160;List</span></a></li>
      <li><a href="pages.html"><span>Examples</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">mbox Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The Xilinx mailbox driver. This driver supports the Xilinx Mailbox device. More detailed description of the driver operation can be found in the <a class="el" href="xmbox_8c.html">xmbox.c</a> file.</p>
<ul>
<li>The Xilinx Mailbox is intended to be used as a bi-directional communication core between a pair of processors. The mailbox API shall allow software to send messages in a FIFO fashion, where the receiver is intended to be software on another processor.</li>
<li>The mailbox implementation provides for a way to "send" and "receive" in an atomic fashion using seperate FIFOs in the mailbox core.</li>
<li>The API itself does not stop the use case where there is more than one sender on the transmit side and more than one receiver on the receiving side (just like TCP/IP sockets). However, unless there is a protocol implemented in the messages being transferred, it is typically good practice to assign just one transmit processor and one receiver processor to a single mailbox.</li>
<li>The API provides for both blocking and non-blocking semantics on the send and receive operations.</li>
</ul>
<p><b>Initialization &amp; Configuration</b></p>
<p>The <a class="el" href="struct_x_mbox___config.html" title="This typedef contains configuration information for the device. ">XMbox_Config</a> structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on HW build properties.</p>
<ul>
<li>XMbox_LookupConfig(DeviceId) - Use the device identifier to find the static configuration structure defined in XMbox_g.c. This is setup by the tools. For some operating systems the config structure will be initialized by the software and this call is not needed. This function returns the CfgPtr argument used by the CfgInitialize function described below.</li>
<li>XMbox_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddress) - Uses a configuration structure provided by the caller. If running in a system with address translation, the provided virtual memory base address replaces the physical address present in the configuration structure. The EffectiveAddress argument is required regardless of operating system environment, i.e. in standalone, CfgPtr-&gt;BaseAddress is recommended, not the xparameters.h #define.</li>
</ul>
<p><b>Interrupts</b></p>
<p>The Mailbox hardware has two interrupt outputs, one for each interface.</p>
<p>For an interface that uses Direct FSL the associated interrupt pin shall be high while there is data in the FIFO for this interface.</p>
<p>For a PLB interface there shall be 3 associated interrupt sources that can be controlled through dedicated registers. Each of these sources shall be associated with a specific bit position in the related register. The sources shall be: Send Threshold Interrupt (STI), Receive Threshold Interrupt (RTI) and FIFO Error (ERR). RTI is set when the number of entries in the receive FIFO become greater than the RIT value (rising edge on RTA). STI is set when the number of entries in the send FIFO becomes equal or less than the SIT value (rising edge on STA). RTI and STI are only set when their respective conditions goes from false to true, not continuously when the condition is fulfilled.</p>
<p>The Mailbox driver does not have an interrupt service routine. It is the responsibility of the caller of Mailbox functions to manage the interrupt including connecting to the interrupt and enabling/disabling the interrupt. The user can create a handler to service the interrupts generated by the Mailbox IP.</p>
<p>Using the Blocking version of the Read function is not recommended since the processor will hang until the requested length is received, which might be quite a long time.</p>
<dl class="section note"><dt>Note</dt><dd></dd></dl>
<p>This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.</p>
<p>Possible Optimization technique: If the interface for the hardware is only expected to be the memory mapped or the FSL interface for the lifetime of the project, it is reasonable to remove the other, unused, leg through the functions which allow access to the other interface method, i.e. if FSL is the only available interface the memory mapped clause in the if statements can be removed improving the performance some due to the lack of the test and branch.</p>
<pre>
 MODIFICATION HISTORY:</pre><pre> Ver   Who  Date     Changes
</p>
<hr/>
<p>
 1.00a va            First release
 1.00a ecm  06/01/07 Cleanup, new coding standard, check into XCS
                        Converted to new XPS hardware.
 1.01a ecm  08/19/08 Fixed CRs 466320, 466322, 476535, 476242, 476243
                        new rev
 2.00a hm   04/09/09 Added support for mailbox v2.0, which has interrupts
                      Fixed CR 502464, which removed extra
                      definitions that are not associated with
                      the interface.
                      Fixed the canonical definition so that each
                      interface is considered as a device instance.
 3.01a sdm  05/06/10 New driver to support AXI version of the core and
                      cleaned up for coding guidelines.
 3.02a bss  08/18/12 Updated tcl script to support Zynq system and AXI stream
                      interface for CR 672073 and CR 655224 respectively.
                      Added XMbox_GetStatus API for CR 676187
 3.03a bss   01/30/13 Updated driver tcl to fix CR#687103 and CR#688715
 3.04a bss   05/13/13 Updated test app tcl to display message that Peripheral
                       tests will not be run if there is only one Processor
                       in design CR#715626
 4.0   adk  19/12/13 Updated as per the New Tcl API's
 4.1   sk   11/10/15 Used UINTPTR instead of u32 for Baseaddress CR# 867425.
                     Changed the prototypes of XMbox_CfgInitialize API.
       ms   01/23/17 Modified xil_printf statement in main function for all
                     examples to ensure that "Successfully ran" and "Failed"
                     strings are available in all examples. This is a fix
                     for CR-965028.
       ms   03/17/17 Added readme.txt file in examples folder for doxygen
                     generation.
       ms   04/05/17 Added tabspace for return statements in functions of
                     mbox examples for proper documentation while
                     generating doxygen and modified filename tag to
                     include them in doxygen examples.
 4.2   ms   04/18/17 Modified tcl file to add suffix U for all macros
                     definitions of mbox in xparameters.h
       ms   08/07/17 Fixed compilation warnings in <a class="el" href="xmbox__sinit_8c.html">xmbox_sinit.c</a>
 4.3   sa   04/20/17 Support for FIFO reset using hardware control register.
       sd   07/26/17 Modified tcl file to prevent false unconnected flagging.
 4.5   sd   09/03/20 Updated makefile for parallel execution.
 4.6   ht   07/06/23 Added support for system device-tree flow.
</pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
	<p class="footer">&copy; Copyright 2015-2022 Xilinx, Inc. All Rights Reserved.</p>
	<p class="footer">&copy; Copyright 2022-2023 Advanced Micro Devices, Inc. All Rights Reserved.</p>
</div>
</body>
</html>
